v9.10.0

Compare Source

v9.9.1

Compare Source

v9.9.0

Compare Source

Features

• 41d0206 feat: Add support for TS config files (#​18134) (Arya Emami)
• 3a4eaf9 feat: add suggestion to require-await to remove async keyword (#​18716) (Dave)

Documentation

• 9fe068c docs: how to author plugins with configs that extend other configs (#​18753) (Alec Gibson)
• 48117b2 docs: add version support page in the side navbar (#​18738) (Amaresh S M)
• fec2951 docs: add version support page to the dropdown (#​18730) (Amaresh S M)
• 38a0661 docs: Fix typo (#​18735) (Zaina Al Habash)
• 3c32a9e docs: Update yarn command for creating ESLint config (#​18739) (Temitope Ogunleye)
• f9ac978 docs: Update README (GitHub Actions Bot)

Chores

• 461b2c3 chore: upgrade to @eslint/[email protected] (#​18765) (Francesco Trotta)
• 59dba1b chore: package.json update for @​eslint/js release (Jenkins)
• fea8563 chore: update dependency @​eslint/core to ^0.3.0 (#​18724) (renovate[bot])
• aac191e chore: update dependency @​eslint/json to ^0.3.0 (#​18760) (renovate[bot])
• b97fa05 chore: update wdio dependencies for more stable tests (#​18759) (Christian Bromann)

v9.8.0

Compare Source

v9.7.0

Compare Source

Features

• 7bd9839 feat: add support for es2025 duplicate named capturing groups (#​18630) (Yosuke Ota)
• 1381394 feat: add regex option in no-restricted-imports (#​18622) (Nitin Kumar)

Bug Fixes

• 14e9f81 fix: destructuring in catch clause in no-unused-vars (#​18636) (Francesco Trotta)

Documentation

• 9f416db docs: Add Powered by Algolia label to the search. (#​18633) (Amaresh S M)
• c8d26cb docs: Open JS Foundation -> OpenJS Foundation (#​18649) (Milos Djermanovic)
• 6e79ac7 docs: loadESLint does not support option cwd (#​18641) (Francesco Trotta)

Chores

• 793b718 chore: upgrade @​eslint/js@​9.7.0 (#​18680) (Francesco Trotta)
• 7ed6f9a chore: package.json update for @​eslint/js release (Jenkins)
• 7bcda76 refactor: Add type references (#​18652) (Nicholas C. Zakas)
• 51bf57c chore: add tech sponsors through actions (#​18624) (Strek)
• 6320732 refactor: don't use parent property in NodeEventGenerator (#​18653) (Milos Djermanovic)
• 9e6d640 refactor: move "Parsing error" prefix adding to Linter (#​18650) (Milos Djermanovic)

v9.6.0

Compare Source

v9.5.0

Compare Source

v9.4.0

Compare Source

v9.3.0

Compare Source

v9.2.0

Compare Source

v9.1.1

Compare Source

v9.1.0

Compare Source

v9.0.0

Compare Source

v9.3.1

Compare Source

v9.3.0

Compare Source

Features

• The verbose option can now be a function to customize logging. (#​1130)

v9.2.0

Compare Source

This release includes a new set of methods to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows passing and returning almost any message type to/from a Node.js subprocess. Also, debugging IPC is now much easier.

Moreover, a new gracefulCancel option has also been added to terminate a subprocess gracefully.

For a deeper dive-in, please check and share the release post!

Thanks @​iiroj for your contribution, @​SimonSiefke and @​adymorz for reporting the bugs fixed in this release, and @​karlhorky for improving the documentation!

Deprecations

• Passing 'ipc' to the stdio option has been deprecated. It will be removed in the next major release. Instead, the ipc: true option should be used. (#​1056)

- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});

• The execaCommand() method has been deprecated. It will be removed in the next major release. If most cases, the template string syntax should be used instead.

- import {execaCommand} from 'execa';
+ import {execa} from 'execa';

- await execaCommand('npm run build');
+ await execa`npm run build`;

const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;

const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;

If the file and/or multiple arguments are supplied as a single string, parseCommandString(command) can split that string into an array. More info. (#​1054)

- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';

const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;

// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);

Features

• Add gracefulCancel option and getCancelSignal() method to terminate a subprocess gracefully. error.isGracefullyCanceled was also added. (#​1109)
• Add error.isForcefullyTerminated. It is true when the subprocess was terminated by the forceKillAfterDelay option. (#​1111)
• New methods to simplify exchanging messages between the current process and the subprocess. More info. (#​1059, #​1061, #​1076, #​1077, #​1079, #​1082, #​1083, #​1086, #​1087, #​1088, #​1089, #​1090, #​1091, #​1092, #​1094, #​1095, #​1098, #​1104, #​1107)
  • The current process sends messages with subprocess.sendMessage(message) and receives them with subprocess.getOneMessage(). subprocess.getEachMessage() listens to multiple messages.
  • The subprocess uses sendMessage(message), getOneMessage() and getEachMessage() instead. Those are the same methods, but imported directly from the 'execa' module.
• The ipcInput option sends an IPC message from the current process to the subprocess as it starts. This enables passing almost any input type to a Node.js subprocess. (#​1068)
• The result.ipcOutput array contains all the IPC messages sent by the subprocess to the current process. This enables returning almost any output type from a Node.js subprocess. (#​1067, #​1071, #​1075)
• The error message now contains every IPC message sent by the subprocess. (#​1067)
• The verbose: 'full' option now logs every IPC message sent by the subprocess, for debugging. More info here and there. (#​1063)

Types

• Add ExecaMethod, ExecaNodeMethod and ExecaScriptMethod, ExecaSyncMethod and ExecaScriptSyncMethod types. (#​1066)
• Export the Message type, for IPC. (#​1059)
• Fix type of forceKillAfterDelay: true option. (#​1116)

Bug fixes

• Fix passing a {file} to both the stdin and the stdout or stderr options. (#​1058)
• Fix multiple minor problems with the cancelSignal option. (#​1108)
• Fix accidental publishing of Vim backup files. (#​1074)
• Fix engines.node field in package.json. Supported Node.js version is ^18.19.0 or >=20.5.0. (by @​iiroj) (#​1101)

v9.1.0

Compare Source

Features (types)

• Export TemplateExpression type. (#​1049)

v9.0.2

Compare Source

Bug fixes (types)

• Do not require using --lib dom for TypeScript users (#​1043, #​1044)
• Fix type of the reject option (#​1046)

v9.0.1

Compare Source

Bug fixes (types)

• Fix types not being importable (#​1033) 3bdab60
• Fix complexity bug with types (#​1037) 6cc519b
• Fix complexity bug with types (#​1035) fee011d

v9.0.0

Compare Source

This major release brings many important features including:

• Split the output into lines, or progressively iterate over them.
• Transform or filter the input/output using simple functions.
• Print the output to the terminal while still retrieving it programmatically.
• Redirect the input/output from/to a file.
• Advanced piping between multiple subprocesses.
• Improved verbose mode, for debugging.
• More detailed errors, including when terminating subprocesses.
• Enhanced template string syntax.
• Global/shared options.
• Web streams and Transform streams support.
• Convert the subprocess to a stream.
• New documentation with many examples.

Please check the release post for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.

Thanks @​younggglcy, @​koshic, @​am0o0 and @​codesmith-emmy for your help!

One of the maintainers @​ehmicky is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify Build, Plugins and Configuration for 2.5 years. Feel free to contact him on his website or on LinkedIn!

Breaking changes

• Minimal supported Node.js version is now 18.19.0. (834e372)

• When the encoding option is 'buffer', the output (result.stdout, result.stderr, result.all) is now an Uint8Array instead of a Buffer. For more information, see this blog post. (by @​younggglcy) (#​586)

const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array

• Renamed some of the allowed values for the encoding option. (#​586, #​928)

- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});

- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});

- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});

- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});

- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});

- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});

- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});

• Passing a file path to subprocess.pipeStdout(), subprocess.pipeStderr() and subprocess.pipeAll() has been removed. Instead, a {file: './path'} object should be passed to the stdout or stderr option. (#​752)

- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});

- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});

- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+	stdout: {file: 'output.txt'},
+	stderr: {file: 'output.txt'},
+});

• Passing a writable stream to subprocess.pipeStdout(), subprocess.pipeStderr() and subprocess.pipeAll() has been removed. Instead, the stream should be passed to the stdout or stderr option. If the stream does not have a file descriptor, ['pipe', stream] should be passed instead. (#​752)

- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});

- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});

- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+	stdout: ['pipe', stream],
+	stderr: ['pipe', stream],
+});

• The subprocess.pipeStdout(), subprocess.pipeStderr() and subprocess.pipeAll() methods have been renamed to subprocess.pipe(). The command and its arguments can be passed to subprocess.pipe() directly, without calling execa() a second time. The from piping option can specify 'stdout' (the default value), 'stderr' or 'all'. (#​757)

- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);

- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});

- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});

• Renamed the signal option to cancelSignal. (#​880)

- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});

• Renamed error.killed to error.isTerminated. (#​625)

try {
	await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
		// ...
	}
}

• subprocess.cancel() has been removed. Please use either subprocess.kill() or the cancelSignal option instead. (#​711)

- subprocess.cancel();
+ subprocess.kill();

• Renamed the forceKillAfterTimeout option to forceKillAfterDelay. Also, it is now passed to execa() instead of subprocess.kill(). (#​714, #​723)

- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');

• The verbose option is now a string enum instead of a boolean. false has been renamed to 'none' and true has been renamed to 'short'. (#​884)

- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});

- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});

• The execPath option has been renamed to nodePath. It is now a noop unless the node option is true. Also, it now works even if the preferLocal option is false. (#​812, #​815)

- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});

• The default value for the serialization option is now 'advanced' instead of 'json'. In particular, when calling subprocess.send(object) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. (#​905)

- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});

• If subprocess.stdout, subprocess.stderr or subprocess.all is manually piped, the .pipe() call must now happen as soon as subprocess is created. Otherwise, the output at the beginning of the subprocess might be missing. (#​658, #​747)

const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
	subprocess.stdout.pipe(process.stdout);
- }, 0);

• Signals passed to subprocess.kill() and to the killSignal option cannot be lowercase anymore. (#​1025)

- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});

- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');

Features

Execution

• Use the template string syntax with any method (including execa()), as opposed to only $. Conversely, $ can now use the regular array syntax. (#​933)
• A command's template string can span multiple lines. (#​843)
• Share options between multiple calls, or set global options, by using execa(options). (#​933, #​965)
• Pass a file URL (as opposed to a file path string) to execa(), execaNode(), the inputFile option, the nodePath option or the shell option. (#​630, #​631, #​632, #​635)

Text lines

• Split the output into text lines by using the lines option. (#​741, #​929, #​931, #​948, #​951, #​957)
• Subprocess is now an async iterable, iterating over the output lines while the subprocess is running. (#​923)

Piping multiple subprocesses

• Simpler syntax: pass the command directly to subprocess.pipe() without calling execa(). A template string can also be used. (#​840, #​859, #​864)
• Wait for both subprocesses to complete. Error handling has been improved too. (#​757, #​778, #​834, #​854)
• Retrieve the result of each subprocess (not only the last one) by using result.pipedFrom and error.pipedFrom. (#​834)
• Pipe 1 or many subprocesses to 1 or many subprocesses. (#​834)
• Pipe subprocesses using other file descriptors than stdin/stdout/stderr by using the from and to piping options. (#​757, #​834, #​903, #​920)
• Cancel piping subprocesses by using the unpipeSignal piping option. (#​834, #​852)

Input/output

• Pass an array with multiple values to the stdin, stdout and stderr options. For example, stdout: ['inherit', 'pipe'] prints the output to the terminal while still returning it as result.stdout. (#​643, #​765, #​941, #​954)
• Redirect the input/output from/to a file by passing a {file: './path'} object or a file URL to the stdin, stdout or stderr option. (#​610, #​614, #​621, #​671, #​1004)
• Transform or filter the input/output by passing a generator function to the stdin, stdout or stderr option. (#​693, #​697, #​698, #​699, #​709, #​736, #​737, #​739, #​740, #​746, #​748, #​755, #​756, #​780, #​783, #​867, #​915, #​916, #​917, #​919, #​924, #​926, #​945, #​969)
• Provide some binary input by passing an Uint8Array to the input or stdin option. (834e372, #​670, #​1029)
• Provide some progressive input by passing a sync/async iterable to the stdin option. (#​604, #​944)
• Provide multiple inputs by combining the stdin, input and inputFile options. (#​666)
• Return other file descriptors than result.stdout and result.stderr by using result.stdio. (#​676)
• Specify different values for stdout and stderr with the following options: verbose, lines, stripFinalNewline, maxBuffer, buffer. (#​966, #​970, #​971, #​972, #​973, #​974)

Streams

• Redirect the input/output from/to a web stream by passing a ReadableStream or WritableStream to the stdin, stdout or stderr option. (#​615, #​619, #​645)
• Transform or filter the input/output by passing a Duplex, Node.js Transform or web TransformStream to the stdin, stdout or stderr option. (#​937, #​938)
• Convert the subprocess to a stream by using subprocess.readable(), subprocess.writable() or subprocess.duplex(). (#​912, #​922, #​958)

Verbose mode

• Print the subprocess' completion, duration and errors with the verbose: 'short' or verbose: 'full' option. (#​887, #​890)
• Print the subprocess' output with the verbose: 'full' option. (#​884, #​950, #​962, #​990)
• Prettier formatting and colors with the verbose option. (#​883, #​893, #​894)

Debugging

• Retrieve the subprocess' duration by using result.durationMs and error.durationMs. (#​896)
• Retrieve the subprocess' current directory by using result.cwd. Previously only error.cwd was available. Also, result.cwd and error.cwd are now normalized to absolute file paths. (#​803)
• Printing result.escapedCommand in a terminal is now safe. (#​875)

Errors

• The ExecaError and ExecaSyncError classes are now exported. (#​911)
• Find the subprocess failure's root cause by using error.cause. (#​911)
• Know whether the subprocess failed due to the maxBuffer option by using error.isMaxBuffer. (#​963)
• Improved error.message: error.stdout and error.stderr are now interleaved if the all option is true. Additional file descriptors are now printed too. Also, the formatting has been improved. (#​676, #​705, #​991, #​992)
• Control characters in error.message are now escaped, so they don't result in visual bugs when printed in a terminal. (#​879)
• Improved stack trace when an error event is emitted on subprocess.stdout or subprocess.stderr. (#​814)

Termination

• Specify an error message or stack trace when terminating a subprocess by passing an error instance to subprocess.kill(). (#​811, #​836, #​1023)
• The forceKillAfterDelay and killSignal options now apply to terminations due not only to subprocess.kill() but also to the cancelSignal, timeout, maxBuffer and cleanup options. (#​714, #​728)

Node.js files

• Use the nodePath and nodeOptions options with any method, as opposed to only execaNode(), by passing the node: true option. (#​804, #​812, #​815)
• When using execaNode() or the node: true option, the current Node.js version is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the same Node.js version. (#​812, #​815, #​1011)

Synchronous execution

• Use the all and buffer: false options with execaSync(), as opposed to only execa(). (#​953, #​956)
• Added the $.s alias for $.sync. (#​594)

Inter-process communication

• Use the ipc: true option, as opposed to the more verbose stdio: ['pipe', 'pipe', 'pipe', 'ipc'] option. (#​794)

Input validation

• Improved the validation of the input, timeout, cwd, detached, cancelSignal and encoding options. (#​668, #​715, #​803, #​928, #​940)
• Improved the validation of the arguments passed to execa() and the other exported methods. (#​838, [#&#820